Google Tag Manager

To use Google Tag Manager (GTM) for sending click and conversion events to the Algolia Insights API, you need to add data attributes to your website’s templates and configure the Algolia Insights template in the GTM dashboard.

Update your search parameters

To connect events to searches, including those from category pages, you must pass queryID when sending search-related events to the Insights API, such as with the clickedObjectIDsAfterSearch method. To include the queryID in the search response, set clickAnalytics to true. To identify users, add the userToken parameter.

index.search('YourSearchQuery', {
    userToken: 'user-1',
    clickAnalytics: true
}).then(({ hits, queryID }) => {
    console.log(hits, queryID);
})

Update your HTML

Add the following data attributes to your template for Algolia search results within your HTML:

data-insights-index. Select a parent DOM element that contains both your filters and hits UI elements to capture events related to both.
data-insights-object-id. The unique object identifier for the Algolia hit.
data-insights-position. The position in the search results, starting with 1 and taking paginated search results into account.
data-insights-query-id. A unique identifier for relating the search query and event.

For more information, see the Insights API reference.

const indexName = <YourIndexName>;

index.search('query', {
    userToken: 'user-1',
    clickAnalytics: true
}).then(({ hits, queryID, page, hitsPerPage }) => {
    const container = document.querySelector('<YourSelector>');

    container.innerHTML = `
    <div data-insights-index="${indexName}">
        <div id="hits">
        ${
            hits.map((hit, arrayIndex) => `
            <div class="hit"
                data-insights-object-id="${hit.objectID}"
                data-insights-position="${arrayIndex + 1 + page * hitsPerPage}"
                data-insights-query-id="${queryID}"
            >
                <!-- ... -->
            </div>
            `).join('')
        }
        </div>
    </div>
    `
});

To track filter events, add a data-insights-filter attribute to each filter element (format: ${attribute}:${value}):

<ul>
    <li data-insights-filter="brand:Apple">Apple</li>
    <li data-insights-filter="brand:HP">HP</li>
    <li>...</li>
</ul>

Send the user token to Google Tag Manager

Send the appropriate user token to GTM when the user’s browser session changes:

JavaScript

window.dataLayer.push({
  algoliaUserToken: 'user-1',
});

If you’re using the search-insights library, use its onUserTokenChange method to sync the user token with GTM:

JavaScript

aa('onUserTokenChange', (userToken) => {
  window.dataLayer.push({
    algoliaUserToken: userToken,
  });
}, { immediate: true });

The onUserTokenChange method is supported in search-insights versions 1.5.0 or later.

Send view events

GTM doesn’t know when users see new search results, as these are rendered client-side on the users’ devices. To inform GTM, you need to manually push view events to the data layer.

index.search('query', { /* ... */ }).then(({ hits, queryID }) => {
    const container = document.querySelector('<your-selector>');
    container.innerHTML = `...`

+  dataLayer.push({ event: 'Hits Viewed' });
});

You can use the Insights option with InstantSearch.js, Vue InstantSearch, or React InstantSearch.

Add the Algolia Search Insights template

Before sending events to the Insights API, add the Algolia Search Insights template to your workspace.

Sign into GTM

Sign in to your GTM workspace and go to Tag Templates > Search Gallery. Search for the Algolia Search Insights template in your Workspace

Select the Algolia template

Search for the Algolia Search Insights template (by Algolia). Select the Algolia Search Insights template in your Workspace

Add template to GTM workspace

Click Add to workspace and confirm by clicking Add. Add the Algolia Search Insights template in your Workspace

Verify addition

On the Tag Templates page, you should now see the Algolia Search Insights template: Algolia Search Insights template added in your Workspace

Add variables

Variables are named placeholders for values that are populated when code is run on your website or app.

Built-in variables

First, add the built-in variable Click Element. This variable is associated with the data from your click events.

Configure variables

In the Variables section of your GTM workspace, click Configure. Configure variable click element in GTM

Select the click element

In the Configure Built-In Variables dialog, select Click Element.

Algolia Insights user token

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New. Add Data Layer variable in GTM

Select data layer

Select Data Layer Variable. Select Data Layer Variable

Add Algolia Insights user token

Enter Algolia Insights User Token as the variable name and algoliaUserToken as the data layer variable name. Add User Token Data Layer variable in GTM

Add User Token Data Layer variable in GTM

Algolia Get Data Attributes

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Select custom JavaScript

Select Custom JavaScript. Add Custom JavaScript variable in GTM

Add JavaScript code

Enter Algolia Get Data Attributes as variable name and add the following JavaScript code:

JavaScript

function() {
  function findClosest(target, selector) {
    while (!target.matches(selector) && !target.matches('body')) {
      target = target.parentElement;
    }
    return target.matches(selector) ? target : undefined;
  }

  return function (attributeName, containerQuerySelector) {
    var clickedElement = {{Click Element}};

    // Search for the selector's children
    var elements = clickedElement
      ? [findClosest(clickedElement, '[' + attributeName +']')]
      : Array.from(document.querySelectorAll((containerQuerySelector || '') + ' [' + attributeName + ']')).filter(Boolean);

    // See if it matches the container itself.
    // For example, `#app[data-insights-index]`
    if (elements.length === 0 && containerQuerySelector) {
      elements = Array.from(document.querySelectorAll(containerQuerySelector + '[' + attributeName + ']')).filter(Boolean);
    }

    var attributes = elements.map(function (element) {
      return element.getAttribute(attributeName);
    });

    return attributes;
  }
}

Algolia Insights index

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript code

Enter Algolia Insights Index as variable name and add the following JavaScript code:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-index')[0];
}

When searching multiple indices, you must specify which index to track. Add an optional query selector with the data-insights-index attribute.For example, if you have the following HTML:

HTML

<div id="index-1" data-insights-index="YourIndexName">
  <div id="hits">
    <!-- ... -->
  </div>
</div>

<div id="index-2">
  <div id="hits">
    <!-- ... -->
  </div>
</div>

Select the div element with the id index-1 for tracking events:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-index', '#index-1')[0];
}

Algolia Insights ObjectIDs

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript

Enter Algolia Insights ObjectIDs as variable name and add the following JavaScript code:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-object-id');
}

When searching multiple indices, you must specify which index to track.

Algolia Insights positions

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript

Enter Algolia Insights Positions as variable name and add the following JavaScript code:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-position');
}

When searching multiple indices, you must specify which index to track.

Algolia Insights QueryID

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript

Enter Algolia Insights QueryID as the variable name and add the following JavaScript code:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-query-id')[0];
}

When searching multiple indices, you must specify which index to track.

Algolia Insights viewed filters

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript

Enter Algolia Insights Viewed Filters as the variable name and add the following JavaScript code:

JavaScript

function() {
  var attributeName = 'data-insights-filter';
  var elements = Array.from(document.querySelectorAll('[' + attributeName + ']'));
  var attributes = elements.map(function (element) {
    return element.getAttribute(attributeName);
  });
  return attributes;
}

Algolia Insights clicked filters

User-defined variables

In the Variables section of your GTM workspace, go to the User-Defined Variables section and click New.

Add variable and JavaScript

Enter Algolia Insights Clicked Filters as variable name and add the following JavaScript code:

JavaScript

function() {
  return {{Algolia Get Data Attributes}}('data-insights-filter')
}

When searching multiple indices, you must specify which index to track.

Add custom triggers

Triggers listen to selected types of events on your website or app and tell the tags to fire, when a specified event is detected.

Add a trigger for view events

To capture the view events you send from your website you must add a custom trigger. Add Hits Viewed trigger in GTM

Select the following values for the corresponding fields:

Trigger name: Hits Viewed
Trigger type: Custom Event
Event name: Hits Viewed

Customize triggers for click events

Click or conversion events come from user actions, such as clicks on DOM elements. Consider this template:

HTML

<div data-insights-index="<your-index-name>">
  <div id="hits">
    <article
      class="hit"
      data-insights-object-id="{{objectID}}"
      data-insights-position="{{__position}}"
      data-insights-query-id="{{__queryID}}"
    >
      <h1>{{name}}</h1>
      <p>{{description}}</p>

      <button class="btn-view-details" type="button">
        View Details
      </button>
    </article>
    <!-- ... -->
  </div>
</div>

To configure a click on the View Details button as a trigger in GTM, select Click - All Elements as the trigger type and configure the trigger to fire only when the click text matches View Details. Add custom trigger with text matching in GTM

Add custom trigger with text matching in GTM

You can also configure the trigger to fire when the click target matches a CSS selector: Add custom trigger with matching CSS selector matching in GTM

Add custom trigger with matching CSS selector matching in GTM

Customize triggers for filters

To track clicked filters, create a trigger that matches the CSS selector of your filter elements. Consider this template:

HTML

<div class="ais-RefinementList">
  <ul class="ais-RefinementList-list">
    <li class="ais-RefinementList-item">
      <div>
        <label data-insights-filter="brand:Apple">
          <input type="checkbox" value="Apple" />
          <span class="ais-RefinementList-labelText">Apple</span>
          <span class="ais-RefinementList-count">746</span>
        </label>
      </div>
    </li>
    <li class="ais-RefinementList-item">
      <!-- ... -->
    </li>
    <!-- ... -->
  </ul>
</div>

In this example, the CSS selector can be .ais-RefinementList-labelText. You must add the data-insights-filter attribute to the element matching the .ais-RefinementList-labelText selector, or to a parent element at a higher level in the DOM.

Set up tags

Tags are the functions that run when a trigger is fired. When using GTM with Algolia, each tag corresponds to an API method for sending a specific event.

Set up your initialization tag

You must set up an initialization tag to connect with the Algolia Insights API.

Algolia Search Insights tag

In your GTM workspace, go to the Tags section and select Algolia Search Insights.

Enter credentials

In the Init Options section, enter your Algolia application ID and API key with search permissions.

Add trigger

In the Triggering section, select Initialization—All Pages to trigger this tag on all pages. Initialization tag in GTM

Set up view tags for objects

This tag sends a view event to the Algolia Insights API when search results are rendered. It corresponds to the viewedObjectIDs method. Viewed Object IDs tag in GTM

Attributes:

Trigger: Hits Viewed
Tag type: Algolia Search Insights
Tag method: Viewed Object IDs
Event name: select any name for your events but name your events consistently.

Set up view tags for filters

This tag sends a view event to the Algolia Insights API when a filter is applied to the search query. It corresponds to the viewedFilters method. Attributes:

Trigger: Hits Viewed
Tag type: Algolia Search Insights
Tag method: Viewed Filters
Filters: {{Algolia Insights Viewed Filters}}
Event name: select any name for your events but name your events consistently.

This tag sends a click event to capture a search query and the clicked items and their positions. It corresponds to the clickedObjectIDsAfterSearch method.

Clicked Object IDs After Search tag in GTM

Attributes:

Trigger: View Details
Tag type: Algolia Search Insights
Tag method: Clicked Object IDs After Search

Set up click tags for objects

This tag sends a click event to the Insights API when users select an item from an Algolia index, regardless of the associated query. This event can be useful on product detail pages or the shopping cart. This tag corresponds to the clickedObjectIDs method. Attributes:

Trigger: View Details
Tag type: Algolia Search Insights
Tag method: Clicked Object IDs

Set up click tags for filters

This tag sends a click event to the Insights API to capture selected filters. It accepts the {{Algolia Insights Clicked Filters}} attribute and corresponds to the clickedFilters method. Attributes:

Trigger: View Details
Tag type: Algolia Search Insights
Tag method: Clicked Filters

Set up conversion tags

The following tags send a conversion event to the Insights API:

Search-related objects. Captures a search query and the converted items. It corresponds to the convertedObjectIDsAfterSearch method. Set up this tag like the related click tag.
Objects. Captures items, regardless of the associated query. It corresponds to the convertedObjectIDs method. Set up this tag like the related click tag.
Filters. Captures converted filters. It corresponds to the convertedFilters method. Set up this tag like the related click tag.

Track add-to-cart and purchase events

If you have an ecommerce website, use conversion tags to track add-to-cart and purchase conversion events. This enhances Algolia’s AI and unlocks features such as revenue analytics. Configure the additional event subtype, value, currency, and object data (price, discount, quantity) attributes for add-to-cart and purchase events. To track purchases of multiple items that are associated with different searches, use the Objects tag and specify the query ID values within the object data attribute. For example, if your object IDs list is ["product-1", "product-2"], then your object data list might look like:

JSON

[
  { "queryID": "query-1", "price": 10, "quantity": 1, "discount": 0 },
  { "queryID": "query-2", "price": 5, "quantity": 2, "discount": 15.5 }
]

Support for add-to-cart and purchase events was added on December 4, 2023. For template update instructions, refer to the GTM documentation.

Submit your changes and debug your events

After setting up the variables, tags, and triggers, submit your changes. To ensure all variables are set correctly, use Google Tag Assistant. Ensure all Algolia variables have the expected values

Ensure all Algolia variables have the expected values

The next step is to validate your events.

Home

Launchpad

Get started

Send events

Send and manage data

Manage results

Personalization

Algolia Recommend

Algolia AI

Update your search parameters

Update your HTML

Send the user token to Google Tag Manager

Send view events

Add the Algolia Search Insights template

Add variables

Built-in variables

Algolia Insights user token

Algolia Get Data Attributes

Algolia Insights index

Algolia Insights ObjectIDs

Algolia Insights positions

Algolia Insights QueryID

Algolia Insights viewed filters

Algolia Insights clicked filters

Add custom triggers

Add a trigger for view events

Customize triggers for click events

Customize triggers for filters

Set up tags

Set up your initialization tag

Set up view tags for objects

Set up view tags for filters

Set up click tags for objects

Set up click tags for filters

Set up conversion tags

Track add-to-cart and purchase events

Submit your changes and debug your events

Home

Launchpad

Get started

Send events

Send and manage data

Manage results

Personalization

Algolia Recommend

Algolia AI

​Update your search parameters

​Update your HTML

​Send the user token to Google Tag Manager

​Send view events

​Add the Algolia Search Insights template

​Add variables

​Built-in variables

​Algolia Insights user token

​Algolia Get Data Attributes

​Algolia Insights index

​Algolia Insights ObjectIDs

​Algolia Insights positions

​Algolia Insights QueryID

​Algolia Insights viewed filters

​Algolia Insights clicked filters

​Add custom triggers

​Add a trigger for view events

​Customize triggers for click events

​Customize triggers for filters

​Set up tags

​Set up your initialization tag

​Set up view tags for objects

​Set up view tags for filters

​Set up click tags for objects related to search

​Set up click tags for objects

​Set up click tags for filters

​Set up conversion tags

​Track add-to-cart and purchase events

​Submit your changes and debug your events

Update your search parameters

Update your HTML

Send the user token to Google Tag Manager

Send view events

Add the Algolia Search Insights template

Add variables

Built-in variables

Algolia Insights user token

Algolia Get Data Attributes

Algolia Insights index

Algolia Insights ObjectIDs

Algolia Insights positions

Algolia Insights QueryID

Algolia Insights viewed filters

Algolia Insights clicked filters

Add custom triggers

Add a trigger for view events

Customize triggers for click events

Customize triggers for filters

Set up tags

Set up your initialization tag

Set up view tags for objects

Set up view tags for filters

Set up click tags for objects related to search

Set up click tags for objects

Set up click tags for filters

Set up conversion tags

Track add-to-cart and purchase events

Submit your changes and debug your events